1   /*
2    * Copyright (C) 2011 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5    * in compliance with the License. You may obtain a copy of the License at
6    *
7    * http://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software distributed under the License
10   * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11   * or implied. See the License for the specific language governing permissions and limitations under
12   * the License.
13   */
14  
15  package com.google.common.hash;
16  
17  import com.google.common.annotations.Beta;
18  
19  import java.io.Serializable;
20  
21  /**
22   * An object which can send data from an object of type {@code T} into a {@code PrimitiveSink}.
23   * Implementations for common types can be found in {@link Funnels}.
24   *
25   * <p>Note that serialization of {@linkplain BloomFilter bloom filters} requires the proper
26   * serialization of funnels. When possible, it is recommended that funnels be implemented as a
27   * single-element enum to maintain serialization guarantees. See Effective Java (2nd Edition),
28   * Item 3: "Enforce the singleton property with a private constructor or an enum type". For example:
29   * <pre>   {@code
30   *   public enum PersonFunnel implements Funnel<Person> {
31   *     INSTANCE;
32   *     public void funnel(Person person, PrimitiveSink into) {
33   *       into.putUnencodedChars(person.getFirstName())
34   *           .putUnencodedChars(person.getLastName())
35   *           .putInt(person.getAge());
36   *     }
37   *   }}</pre>
38   *
39   * @author Dimitris Andreou
40   * @since 11.0
41   */
42  @Beta
43  public interface Funnel<T> extends Serializable {
44  
45    /**
46     * Sends a stream of data from the {@code from} object into the sink {@code into}. There
47     * is no requirement that this data be complete enough to fully reconstitute the object
48     * later.
49     *
50     * @since 12.0 (in Guava 11.0, {@code PrimitiveSink} was named {@code Sink})
51     */
52    void funnel(T from, PrimitiveSink into);
53  }